Gold Medal Software 2

home *** CD-ROM | disk | FTP | other *** search

/ Gold Medal Software 2 / Gold Medal Software Volume 2 (Gold Medal) (1994).iso / bbsutils / sappha.arj / EXTERN.DOC < prev next >

Wrap

Text File | 1994-01-01 | 16KB | 346 lines

=========================================================================== === === === DOORS AND EVENTS === === === =========================================================================== The information presented in this chapter is addressed to experienced sysops. If you are new to the joys of sysoping, it would probably be best to avoid the DOORS and EVENTS commands until you are more familiar with your new BBS. Sapphire will function perfectly well without DOORS and EVENTS installed, so you can safely skip this chapter and come back to it later. This chapter gives a good overview of doors and events. A detailed explanation of door processing is available in the HOWDOOR tutorial, which is shipped with registered copies of Sapphire. You can also obtain HOWDOOR by calling our support BBS at 514-345-8654. ----------- DEFINITIONS ----------- Doors and events are both instances where the Sapphire program ends and control is returned back to DOS. In the case of a door, the shut-down is initiated by a user; for events, the shut-down happens automatically, ac- cording to a schedule you set up. --------------------------------- APPLICATIONS FOR EVENT PROCESSING --------------------------------- Consider the following batch file. (Note that the <-- arrow and following text are comments, not part of the batch file.) REM Batch File Autoback <-- A batch file comment (REMark) :START <-- A batch file label SRUN <-- The main Sapphire program COPY SAPPHIRE.USR A:SAPPHIRE.SAV <-- Copy the user list GOTO START <-- Start over again If you could arrange to have the BBS come down every night at 3:00, it could make a spare copy of the user list on the A: drive. This would be very useful, although of course you would have to make sure that the A: drive always had a floppy inserted and ready to go! Set up in this way, you could leave town for a long weekend, confident that the user list was being backed up every day. NOTE: The example actually contains some inaccuracies. In an actual event batch file, only the COPY line would be necessary; the rest of the batch file would be "understood" by Sapphire. See "How EXTERNAL.BAT Works" for details.) Another possible application is automatic dial-out via your favourite communications program (to pick up mail, perhaps). Of course, you would have to write a "script" (i.e. a program that your communications program understands) in order to have it dial out, sign on, pick up the mail, then return to DOS. One very common use for event processing is to support network systems such as Fido -- a very complicated topic beyond the scope of this manual. --------------------------------- APPLICATIONS FOR DOORS PROCESSING --------------------------------- A door is an external program that a user can run from Sapphire. A door program is designed to handle its own modem communications -- Sapphire is not running when the door program is in operation. IMPORTANT: A door is NOT an ordinary DOS program. DOS programs are NOT designed to be run as doors. You can use certain shareware utilities to make SOME DOS programs work as doors, but most do not. There are dozens of door programs available. One example is the Pyroto Mountain gaming system, which (like Sapphire) was written by Pinnacle Software. You can call it as a door, giving your members a chance to play this intriguing game of magic and politics. We also publish the Free Speech "open forum" system, which can be run as a door. Before making a door available to your members, you should review it care- fully. The quality of door software varies greatly; some may crash, thereby failing to return to DOS and consequently taking your BBS "off the air". In order to run most doors (i.e. those not created by Pinnacle Software), you will require a door-data conversion program such as DoorMaster or DoorWay or a specific converter program such as SP2QBBS. The latest version of these converters can usually be obtained from our support BBS, or your local or national BBS, or from a telecomputing service such as GEnie or CompuServe. If you call our BBS, check the files list for special tutorials on door techniques. ----------------------- CODING YOUR BATCH FILES ----------------------- In an environment using doors and events or both, everything is tied together with batch (.BAT) files. (For detailed information about batch files, consult your DOS reference manual.) The simplest kind of batch file was illustrated in the "automatic user list back-up" example shown earlier. This was a just a loop, executing one function. One problem, though ... you'll note that there was no way to get out of the loop! So it was not a particularly useful program. If you want to call Sapphire from any directory, put a batch file like the following one (which you could call S.BAT) in one of the directories in your PATH: ECHO OFF <-- Stop display of batch lines C: <-- Change to the right drive CD \SAPPHIRE <-- Change to your Sapphire directory SAPPHIRE %1 %2 <-- Jump to batch file SAPPHIRE.BAT SAPPHIRE.BAT is a batch file that comes with Sapphire. It looks like this: ECHO OFF <-- Stop display of batch lines SAPPHIRE %1 %2 <-- Start up Sapphire EXTERNAL <-- Jump to batch file EXTERNAL.BAT This batch file must be in the directory where SRUN.EXE resides. The %1 and %2 after the SAPPHIRE allows you to pass parameters to Sapphire, so you can start up the batch file with SAPPHIRE LOCAL to run without a modem. (This is how the SYSOP batch file does it.) ---------------------- HOW EXTERNAL.BAT WORKS ---------------------- Don't look for a file named EXTERNAL.BAT in the Sapphire package -- there isn't one. EXTERNAL.BAT is created whenever Sapphire ends. If Sapphire is shutting down because you are closing it (using the CLOSE command, for example), EXTERNAL.BAT will be empty. As a result, you'll drop straight through to the DOS prompt. For a doors or an event, however, Sapphire copies the associated batch file into EXTERNAL.BAT. So whatever was in the associated batch file will get executed. But how does this get us back to Sapphire? After Sapphire copies the other batch file into EXTERNAL.BAT, it appends some additional instructions, as in this example: C: <-- Switch to Sapphire's "home" drive CD \SAPPHIRE <-- Switch to Sapphire's "home" directory SAPPHIRE <-- Jump to the SAPPHIRE.BAT batch file And thus, the circle is completed. Of course, the extra instructions may vary, depending on where your copy of SRUN.EXE resides and the way you started up Sapphire. --------------- BATCH TEMPLATES --------------- You will use the DOORS and EVENTS commands to specify which batch files will be copied to EXTERNAL.BAT. We will call these files "Batch Tem- plates", because although they end in .BAT, they are never actually run directly; they are copied to EXTERNAL.BAT, as explained previously. You can write the templates without regard to what happens after the program ends, because that's taken care of when Sapphire copies them to EXTERNAL.BAT. NOTE: A template must not call another batch file, unless that batch file contains the code to get back to SAPPHIRE.BAT. You can, however, use the batch file command "CALL", which is explained in your DOS reference manual. Sapphire's method of handling batch files as templates makes for very simple batch files for doors and events. For example, to call up the PYROTO door, you could write a template file named PYROTO.BAT, which contains only three lines: C: <-- Make sure you are on the right drive CD \PYROTO <-- Change to the Pyroto directory PYROTO <-- Start up the program ------------------------------- WRITING DOOR AND EVENT PROGRAMS ------------------------------- When Sapphire calls a door or event, it creates a file in the root directory, named SAPPHIRE.DAT. This file contains important information for doors and events. If you plan to write door or event programs, you'll need access to this data. Turbo Pascal source code describing the layout of the file is available in the file named SDOOR.INC, included in the SAPPHC (optional material) file set. =========================================================================== === === === FILE TRANSFER === === === =========================================================================== ---------------------- WHAT IS FILE TRANSFER? ---------------------- With Sapphire's file-transfer feature installed (see SYSOP:DSZ), you will be able to exchange software with people who dial into your system, using the popular Xmodem, Ymodem and Zmodem protocols. Sapphire maintains a list of up to 500 programs (providing there is enough space on your hard disk), along with statistics and documentation. The file-transfer feature requires a system equipped with a hard-disk with a minimum of 1 Megabyte free space. ------------------------ INSTALLING FILE TRANSFER ------------------------ In order to enable file-transfer (Xmodem, Ymodem and Zmodem), you must install the DSZ file-transfer program, which is included in the Sapphire package with the permission of its author, Chuck Forsberg. You can install DSZ via SYSOP:DSZ (i.e. select the DSZ option on the main menu of the SYSOP utility). This will enable the GET, GIVE, PROTOCOL and FILES commands. ----------------------- ADDING SOFTWARE LOCALLY ----------------------- To add a file to the software collection while you are at the console, you must first place the file in the files directory (which is usually named C:\SAPPHIRE\FILES). Sapphire's DOS command comes in handy here, for moving files around. Afterwards, use the GIVE command. For example, if you had moved the file PYROTO.LZH into the files directory, you would then enter this command: ==> GIVE PYROTO.LZH You would then be asked who this file is for (everybody, sysop, etc.), then asked to write some documentation about the file. (This step is described later, in more detail.) ------------------------ ADDING SOFTWARE REMOTELY ------------------------ A remote user follows essentially the same steps as a local user, but obviously he cannot place the file directly into the files directory. So he must upload the file, using one of the file-transfer protocols used by Sapphire (Xmodem-Checksum, Xmodem-CRC, Ymodem, Zmodem). As a reward for contributing software, he is granted "double-your-minutes- back for this visit and the next". For example, if it took him 10 minutes, he gets an extra 20 minutes for the current visit, plus 20 extra minutes for the next session. ------------------------------ HOW ONLINE DOCUMENTATION WORKS ------------------------------ After contributing a file, the contributor may write up to 48 lines of documentation, which other people will be able to read before deciding whether or not to download this file. Online documentation that has already been written can be re-used. For example, if you are making available a multi-file software package, you can tell Sapphire to use one documentation file for all of the files. Incidentally, if one of those software files is deleted, the documentation file is retained -- as long as some other file is using it. The documentation step uses the usual text editor that you use for writing messages. No new skills need be learned. In fact, you can even include private and exclusive messages in your documentation. NOTE: If the entire documentation is private (i.e. the first line, [summary line] is private), then the file can be accessed only by the people listed in the private header. This enables you to exchange files privately with a limited group of people. The documentation is saved in the files directory, in a file with the same root-name as the original file. For example, a file named VARITALE.ARC would have a documentation file named VARITALE.S-D associated with it. (The S-D extension stands for Software Documentation.) If you don't like the documentation that a user has written, you can copy some better documentation over the S-D file. All S-D files are standard text files, prepared with a text editor. If you don't like the extension S-D, you can change it to something else, using SYSOP:CONFIG:ADVANCED:GENERAL:PATHS. ------------------ TRANSFER PROTOCOLS ------------------ The Ymodem supported by Sapphire is proper Ymodem, per the original specif- ication. Some very respectable communications programs confuse the proto- col Xmodem-1K with Ymodem. If your users complain that Ymodem doesn't work for them, suggest they switch their communications program from Ymodem to Ymodem-Batch. You should encourage your users to use the Zmodem protocol, because it has built-in crash recovery. That means that if the user is cut off while downloading a file, he can call back and pick up where he left off. Crash recovery also works on uploaded files. If the user is disconnected during an Xmodem or Ymodem transfer, Sapphire has no choice but to delete the partial file. But if the user used Zmodem, Sapphire retains the partial file in the files directory -- though it does not add it to the files list. This enables the user to call back and pick up where he left off, using Zmodem's crash recovery.